＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

                        PC-FXGAオーサリングソフトウェア
                    『ＧＭＡＫＥＲ』スタータキット(Ver.1.0)
                           ”ＬＩＢＡＧＬ．Ａ”の解説

                                        日本電気ホームエレクトロニクス株式会社
                                                        １９９５年１１月１０日

＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

目次

第１章  はじめに
１．１    AGL概要
１．２    データ型

第２章  オブジェクト制御
２．１    オブジェクトをワールド座標系原点にリセット   AGLResetObj
２．２    オブジェクトをX軸まわりに回転(角度指定)      AGLRotateObjX
２．３    オブジェクトをY軸まわりに回転(角度指定)      AGLRotateObjY
２．４    オブジェクトをZ軸まわりに回転(角度指定)      AGLRotateObjZ
２．５    オブジェクトをX軸まわりに回転(sin,cos指定)   AGLRotateObjXSC
２．６    オブジェクトをY軸まわりに回転(sin,cos指定)   AGLRotateObjYSC
２．７    オブジェクトをZ軸まわりに回転(sin,cos指定)   AGLRotateObjZSC
２．８    オブジェクトを拡大/縮小                      AGLScaleObj
２．９    オブジェクトを移動                           AGLTranslateObj
２．１０  オブジェクトを幾何変換(マトリクス指定)       AGLObjMulMatrix

第３章  マテリアル制御
３．１    ライティングパラメータを確定                 AGLSetMaterial

第４章  ライト制御
４．１    ライト強度の設定                             AGLSetLightStrength
４．２    ライト方向の設定                             AGLSetLightVector
４．３    ライトの強度と方向の設定                     AGLSetLight
４．２    ライト方向のリセット                         AGLResetLight
４．５    ライトをX軸まわりに回転(角度指定)            AGLRotateLightX
４．６    ライトをY軸まわりに回転(角度指定)            AGLRotateLightY
４．７    ライトをZ軸まわりに回転(角度指定)            AGLRotateLightZ
４．８    ライトをX軸まわりに回転(sin,cos指定)         AGLRotateLightXSC
４．９    ライトをY軸まわりに回転(sin,cos指定)         AGLRotateLightYSC
４．１０  ライトをZ軸まわりに回転(sin,cos指定)         AGLRotateLightZSC
４．１１  ライト方向を変換(マトリクス指定)             AGLLightMulMatrix

第５章  カメラ制御
５．１    カメラのリセット                             AGLResetCamera
５．２    カメラをX軸まわりに回転(角度指定)            AGLRotateCameraX
５．３    カメラをY軸まわりに回転(角度指定)            AGLRotateCameraY
５．４    カメラをZ軸まわりに回転(角度指定)            AGLRotateCameraZ
５．５    カメラをX軸まわりに回転(sin,cos指定)         AGLRotateCameraXSC
５．６    カメラをY軸まわりに回転(sin,cos指定)         AGLRotateCameraYSC
５．７    カメラをZ軸まわりに回転(sin,cos指定)         AGLRotateCameraZSC
５．８    カメラの倍率を拡大/縮小                      AGLZoomCamera
５．９    カメラを移動                                 AGLTranslateCamera
５．１０  カメラを注視点に向ける                       AGLLookAtCamera
５．１１  カメラにパースをかける                       AGLPerspectiveCamera
５．１２  カメラマトリクスを幾何変換(マトリクス指定)   AGLCameraMulMatrix

第６章  描画、その他の関数
６．１    AGLとHuC6273の初期化                         AGLInit
６．２    オブジェクト操作を確定                       AGLFixObj
６．３    オブジェクトを描画                           AGLPutObj
６．４    オブジェクトに対する操作を確定して描画       AGLFixPutObj
６．５    フレームをスワップ                           AGLShot

第７章  補足
７．１    AGL使用上の注意
７．２    構造体とグローバル変数について


＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

第１章  はじめに

■１．１    AGL概要

AGLはHuC6273のために書かれた三次元グラフィックスライブラリです。AGLはFARLの機
能を利用しているため、AGLを使用するにはFARLを同時にリンクする必要があります。

AGLの目的は、HuC6273がサポートしていないワールド座標系の概念を導入して複数の
オブジェクトやカメラ、ライトをそれぞれ独立に制御できるような関数群を用意し、
またソースコードを提供することによってHuC6273の三次元グラフィックス機能の基本
的な使用法を学んでいただくことにあります。

AGLはHuC6273の三次元グラフィックス機能をすべて網羅しているわけではありません。
AGLは、カメラやライト、オブジェクトのマトリクスに関する処理を行っているだけな
ので、これら以外のHuC6273に対する指示やシステムの設定は別途行う必要があります。
必要に応じて、HuC6273に関してはFARL、それ以外についてはVLIB等の機能を併用して
ください。FARLについては『LIBFARL.Aの解説』を参照してください。また、HuC6273の
データフォーマット、座標系、コマンド仕様等の詳細についてはHuC6273のマニュアル
を参照してください。


■１．２    データ型

以下のデータ型を agl.h で定義しています。

fix1015       HuC6273が扱う<1.0.15>フォーマットの固定小数点データです。
fix187        HuC6273が扱う<1.8.7>フォーマットの固定小数点データです。


＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

第２章  オブジェクト制御


オブジェクト毎の動き（モデル座標系からワールド座標系への変換）を制御します。

個々のオブジェクトを表す構造体として下記の構造体（以下ではオブジェクト構造体
と呼びます）が定義されています。


typedef struct object {
    int       *geometryTop;         /* AGCオブジェクトデータ格納アドレス*/
    int       geometryLength;       /* オブジェクトデータ長             */
    Material  *material;            /* マテリアル構造体へのポインタ     */
    int       objChanged;           /* マトリクスの変更フラグ           */
    fix187    objToWorld187[4][4];  /* ワールド座標系への変換マトリクス */
    fix1015   objToWorld1015[3][3]; /* ワールド座標系への変換マトリクス */
    short     dummy1;
    fix187    objMatrix[4][4];      /* オブジェクトマトリクス           */
    fix1015   nrmMatrix[3][3];      /* ノーマルマトリクス               */
    short     dummy2;
} object;


この構造体をオブジェクト制御関数に引き渡してオブジェクトの動きを制御し、最終
的にAGLFiXPutObj関数に引き渡すことでオブジェクトの描画が行われます。

ユーザが直接的に設定するメンバーは下記の３つです。


geometryTop     オブジェクトを描画するためにHuC6273に転送する3D描画コマンド
                （AGC形式のモデルデータ）の先頭アドレス。32bit word境界のア
                ドレスでなければなりません。

geometryLength  上記AGCデータの長さ（32bit単位でのword数）。AGCデータが奇数
                の16bit wordである場合、末尾に0x0000(NOP)をパディングして
                32bit word単位に揃える必要があります。

material        オブジェクト表面の質感を表すマテリアルを示します。AGLではマテ
                リアル情報をマテリアル構造体（第３章『マテリアル制御』参照）
                に定義し、このmaterialにはマテリアル構造体を指すポインタを
                セットします。materialにマテリアル構造体のアドレスをセットして
                おくと、オブジェクト描画時にそのマテリアル情報がHuC6273にセッ
                トされて、それにしたがった描画が行われます。materialにNULLを
                セットすると、オブジェクトの描画にあたってHuC6273内部のマテリ
                アル情報は更新されません。それ以前にセットされているマテリアル
                情報にしたがって描画されます。


これ以外のメンバーには、オブジェクトの動きのためのオブジェクトマトリクス、
ノーマルマトリクス等のステータスが保持されます。それらオブジェクトの動きはす
べて関数を通して制御します。


■２．１    オブジェクトをワールド座標系原点にリセット

《名称》
AGLResetObj

《形式》
#include <farl.h>
#include <agl.h>
void AGLResetObj(object *obj)

《パラメータ》
obj :   オブジェクト構造体へのポインタ

《解説》
objが示すオブジェクトをワールド座標系原点にリセットします。

※この関数はマクロです。

《戻り値》
なし


■２．２    オブジェクトをX軸まわりに回転(角度指定)

《名称》
AGLRotateObjX

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateObjX(object *obj, int angle)

《パラメータ》
obj   : オブジェクト構造体へのポインタ
angle : 回転角度 (0〜3599)

《解説》
objが示すオブジェクトをワールド座標系のX軸まわりに回転します。角度angleの単位
は0.1度(degree)で、指定できる値の範囲は 0 〜 3599(0度〜359.9度)です。

《戻り値》
なし


■２．３    オブジェクトをY軸まわりに回転(角度指定)

《名称》
AGLRotateObjY

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateObjY(object *obj, int angle)

《パラメータ》
obj   : オブジェクト構造体へのポインタ
angle : 回転角度 (0〜3599)

《解説》
objが示すオブジェクトをワールド座標系のY軸まわりに回転します。角度angleの単位
は0.1度(degree)で、指定できる値の範囲は 0 〜 3599(0度〜359.9度)です。

《戻り値》
なし


■２．４    オブジェクトをZ軸まわりに回転(角度指定)

《名称》
AGLRotateObjZ

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateObjZ(object *obj, int angle)

《パラメータ》
obj   : オブジェクト構造体へのポインタ
angle : 回転角度 (0〜3599)

《解説》
objが示すオブジェクトをワールド座標系のZ軸まわりに回転します。角度angleの単位
は0.1度(degree)で、指定できる値の範囲は 0 〜 3599(0度〜359.9度)です。

《戻り値》
なし


■２．５    オブジェクトをX軸まわりに回転(sin,cos指定)

《名称》
AGLRotateObjXSC

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateObjXSC(object *obj, fix1015 SinXX, fix1015 CosXX)

《パラメータ》
obj   : オブジェクト構造体へのポインタ
SinXX : sin値 (<1.0.15>)
CosXX : cos値 (<1.0.15>)

《解説》
objが示すオブジェクトをワールド座標系のX軸まわりに回転します。パラメータとし
て、回転角をθとした場合の sinθ と cosθ を<1.0.15>固定小数点フォーマットで
与えます。

《戻り値》
なし


■２．６    オブジェクトをY軸まわりに回転(sin,cos指定)

《名称》
AGLRotateObjYSC

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateObjYSC(object *obj, fix1015 SinYY, fix1015 CosYY)

《パラメータ》
obj   : オブジェクト構造体へのポインタ
SinYY : sin値 (<1.0.15>)
CosYY : cos値 (<1.0.15>)

《解説》
objが示すオブジェクトをワールド座標系のY軸まわりに回転します。パラメータとし
て、回転角をθとした場合の sinθ と cosθ を<1.0.15>固定小数点フォーマットで
与えます。

《戻り値》
なし


■２．７    オブジェクトをZ軸まわりに回転(sin,cos指定)

《名称》
AGLRotateObjZSC

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateObjZSC(object *obj, fix1015 SinZZ, fix1015 CosZZ)

《パラメータ》
obj   : オブジェクト構造体へのポインタ
SinZZ : sin値 (<1.0.15>)
CosZZ : cos値 (<1.0.15>)

《解説》
objが示すオブジェクトをワールド座標系のZ軸まわりに回転します。パラメータとし
て、回転角をθとした場合の sinθ と cosθ を<1.0.15>固定小数点フォーマットで
与えます。

《戻り値》
なし


■２．８    オブジェクトを拡大/縮小

《名称》
AGLScaleObj

《形式》
#include <farl.h>
#include <agl.h>
void AGLScaleObj(object *obj, fix187 sx, fix187 sy, fix187 sz)

《パラメータ》
obj :   オブジェクト構造体へのポインタ
sx  :   X方向の倍率 (<1.8.7>)
sy  :   Y方向の倍率 (<1.8.7>)
sz  :   Z方向の倍率 (<1.8.7>)

《解説》
objが示すオブジェクトをワールド座標系のX,Y,Z方向にそれぞれ sx, sy, sz 倍だけ
相対的に拡大/縮小させます。sx, sy, szはそれぞれ<1.8.7>固定小数点フォーマット
です。

※この関数はマクロです。

《戻り値》
なし


■２．９    オブジェクトを移動

《名称》
AGLTranslateObj

《形式》
#include <farl.h>
#include <agl.h>
void AGLTranslateObj(object *obj, fix187 dx, fix187 dy, fix187 dz)

《パラメータ》
obj :   オブジェクト構造体へのポインタ
dx  :   X方向移動量 (<1.8.7>)
dy  :   Y方向移動量 (<1.8.7>)
dz  :   Z方向移動量 (<1.8.7>)

《解説》
objが示すオブジェクトをワールド座標系のX,Y,Z方向にそれぞれ dx, dy, dzだけ移動
させます。dx, dy, dzはそれぞれ<1.8.7>固定小数点フォーマットです。

※この関数はマクロです。

《戻り値》
なし


■２．１０  オブジェクトを幾何変換(マトリクス指定)

《名称》
AGLObjMulMatrix

《形式》
#include <farl.h>
#include <agl.h>
void AGLObjMulMatrix(object *obj, fix187 m187[4][4], fix1015 m1015[3][3])

《パラメータ》
obj   : オブジェクト構造体へのポインタ
m187  : <1.8.7>フォーマットの4×4マトリクス
m1015 : <1.0.15>フォーマットの3×3マトリクス

《解説》
objが示すオブジェクト構造体のメンバー objToWorld187に対してマトリクスm187を、
objToWorld1015対してm1015を乗算します。任意の幾何変換をオブジェクトに適用する
ことができます。

《戻り値》
なし


＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

第３章  マテリアル制御


オブジェクト表面の質感（マテリアル）を表す構造体として、下記の構造体（以下では
マテリアル構造体と呼びます）が定義されています。

typedef struct Material {
    fix1015    ambient;    /* 環境光反射係数 */
    fix1015    diffuse;    /* 拡散反射係数 */
    fix1015    specular;   /* 鏡面反射係数 */
    fix1015    dummy1;
    fix1015    rmat[5];    /* 実際にHuC6273にセットするパラメータ */
} Material;

マテリアル係数をマテリアル構造体にセットし、そのマテリアル構造体のアドレスを
オブジェクト構造体のメンバー material にセットすることによって、そのマテリア
ル情報がオブジェクトの描画に反映されます（このマテリアル情報と、オブジェクト
の表面の向き、ライトの方向、ライトの強さによって、実際に画面に見える物体表面
の明るさが求められます）。

ユーザが直接的に設定するメンバーは下記の３つです。

ambient         ライトの設定や物体表面の向きによらず必ず物体表面から反射される
                光の強さを設定します。

diffuse         ライトの光が物体表面で全方向に拡散する割合を設定します。

specular        ライトの光が物体表面で単純反射する割合いを設定します。

これらはマテリアル構造体を直接書き換えて制御します。それぞれ<0.0.15>フォーマッ
トの固定小数値で、0x0000以上 0x7fff以下の値を設定します。

rmat には、AGLSetMaterial関数によって、上記３つの値とライトの強度から計算され
たライティングパラメータが格納され、AGLPutObj関数でこの値が HuC6273の TE light
coefficient register にセットされます。AGLSetMaterial関数を明示的に呼び出さな
ければ、上記３つの値やライト強度の変更が実際に反映されませんので注意して下さ
い。

なお、このライティングパラメータは、下記のすべての条件がすべて満たされている
場合にのみ描画に反映されます。

  ・オブジェクトのデータに法線が付いていること

  ・HuC6273のカラーモードがI-Cカラーモードに設定されていること
    (TE control register: ICM=1)

  ・HuC6273のライティング計算がONになっていること
    (TE control register: LTEN=1)

specular の設定は、さらに下記の条件が満たされている場合にのみ有効です。

  ・HuC6273のスペキュラー計算がONになっていること
    (TE control register: SPEN=1)

さらに、テクスチャマッピングされた表面に対してライティングパラメータを反映さ
せるためには下記の設定が必要です。

  ・HuC6273のテクスチャ・ライティング計算がONになっていること
    (PE control register: TLEN=1)


■３．１    ライティングパラメータを確定

《名称》
AGLSetMaterial

《形式》
#include <farl.h>
#include <agl.h>
void AGLSetMaterial(material *mat, int n)

《パラメータ》
mat :   マテリアル構造体配列の先頭アドレス
n   :   マテリアル構造体の個数

《解説》
matからのn個のマテリアル構造体に、現在のマテリアル設定とライト強度の設定を反映
させます。この関数を呼び出して明示的に指示しない限り、ライト強度やマテリアルの
変更がライティングパラメータに反映されません。

《戻り値》
なし


＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

第４章  ライト制御


HuC6273がサポートしている２つのライト（平行光）の強さとワールド座標系での方向
を制御する関数群です。

各関数への引数としてのライト番号は、agl.h内で下記のように定義されています。

#define AGL_LIGHT0    0
#define AGL_LIGHT1    1


■４．１    ライト強度の設定

《名称》
AGLSetLightStrength

《形式》
#include <farl.h>
#include <agl.h>
void AGLSetLightStrength(int ln, fix1015 str)

《パラメータ》
ln  :   ライト番号 (AGL_LIGHT0 または AGL_LIGHT1)
str :   強度 (<0.0.15>)

《解説》
lnが示すライトの強度を str に設定します。str は<0.0.15>フォーマットの固定小数
値で、0x0000以上 0x7fff以下の値を指定します。

ライト強度を変更した場合、マテリアルを持つオブジェクトを描画する前に、
AGLSetMaterial関数を明示的に呼び出して、そのマテリアル情報（ライティングパラ
メータ）を確定させる必要があります（３．１『ライティングパラメータを確定』参
照）。参照

※この関数はマクロです。

《戻り値》
なし


■４．２    ライト方向の設定

《名称》
AGLSetLightVector

《形式》
#include <farl.h>
#include <agl.h>
void AGLSetLightVector(int ln, fix1015 vx, fix1015 vy, fix1015 vz)

《パラメータ》
ln       :      ライト番号
vx,vy,vz :      ベクトル (<1.0.15>)

《解説》
lnが示すライトの方向をワールド座標系で(vx,vy,vz)に設定します。vz,vy,vzは
<1.0.15>フォーマットです。このベクトルは長さ 1 に正規化されている必要がありま
す。光源へ向かうベクトルとしてセットして下さい。

                --------->    ＜光源＞
                (vx,vy,vz)

※この関数はマクロです。

《戻り値》
なし


■４．３    ライトの強度と方向の設定

《名称》
AGLSetLight

《形式》
#include <farl.h>
#include <agl.h>
void AGLSetLight(int ln, fix1015 vx, fix1015 vy, fix1015 vz, fix1015 str)

《パラメータ》
ln       :      ライト番号
vx,vy,vz :      ベクトル (<1.0.15>)
str      :      強度 (<0.0.15>)

《解説》
lnが示すライトの方向をワールド座標系で(vx,vy,vz)に設定し、強度を str に設定し
ます。vz,vy,vzは<1.0.15>フォーマットです。このベクトルは長さ 1 に正規化されて
いる必要があります。str は<0.0.15>フォーマットの固定小数値で、0x0000以上
0x7fff以下の値を指定します。

※この関数はAGLSetLightVectorとAGLSetLightStrengthの2関数をひとまとめにしたマ
クロです。

《戻り値》
なし


■４．４    ライト方向のリセット

《名称》
AGLResetLight

《形式》
#include <farl.h>
#include <agl.h>
void AGLResetLight(int ln)

《パラメータ》
ln :    ライト番号 (AGL_LIGHT0 または AGL_LIGHT1)

《解説》
lnが示すライトのベクトルを(0.0, 0.0, 1.0)に初期化します。ライト強度は変化させ
ません。AGLSetLightVector(ln, 0.0, 0.0, 1.0)と同じです。

※この関数はマクロです。

《戻り値》
なし


■４．５    ライトをX軸まわりに回転(角度指定)

《名称》
AGLRotateLightX

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateLightX(int ln, int angle)

《パラメータ》
ln    : ライト番号 (AGL_LIGHT0 または AGL_LIGHT1)
angle : 回転角度 (0〜3599)

《解説》
lnが示すライトをワールド座標系のX軸まわりに回転します。角度angleの単位は0.1度
(degree)で、指定できる値の範囲は 0 〜 3599(0度〜359.9度)です。

《戻り値》
なし


■４．６    ライトをY軸まわりに回転(角度指定)

《名称》
AGLRotateLightY

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateLightY(int ln, int angle)

《パラメータ》
ln    : ライト番号 (AGL_LIGHT0 または AGL_LIGHT1)
angle : 回転角度 (0〜3599)

《解説》
lnが示すライトをワールド座標系のY軸まわりに回転します。角度angleの単位は0.1度
(degree)で、指定できる値の範囲は 0 〜 3599(0度〜359.9度)です。

《戻り値》
なし


■４．７    ライトをZ軸まわりに回転(角度指定)

《名称》
AGLRotateLightZ

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateLightZ(int ln, int angle)

《パラメータ》
ln    : ライト番号 (AGL_LIGHT0 または AGL_LIGHT1)
angle : 回転角度 (0〜3599)

《解説》
lnが示すライトをワールド座標系のZ軸まわりに回転します。角度angleの単位は0.1度
(degree)で、指定できる値の範囲は 0 〜 3599(0度〜359.9度)です。

《戻り値》
なし


■４．８    ライトをX軸まわりに回転(sin,cos指定)

《名称》
AGLRotateLightXSC

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateLightXSC(int ln, fix1015 SinXX, fix1015 CosXX)

《パラメータ》
ln    : ライト番号 (AGL_LIGHT0 または AGL_LIGHT1)
SinXX : sin値 (<1.0.15>)
CosXX : cos値 (<1.0.15>)

《解説》
lnが示すライトをワールド座標系のX軸まわりに回転します。パラメータとして、回転
角をθとした場合の sinθ と cosθ を<1.0.15>固定小数点フォーマットで与えます。

《戻り値》
なし


■４．９    ライトをY軸まわりに回転(sin,cos指定)

《名称》
AGLRotateLightYSC

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateLightYSC(int ln, fix1015 SinYY, fix1015 CosYY)

《パラメータ》
ln    : ライト番号 (AGL_LIGHT0 または AGL_LIGHT1)
SinYY : sin値 (<1.0.15>)
CosYY : cos値 (<1.0.15>)

《解説》
lnが示すライトをワールド座標系のY軸まわりに回転します。パラメータとして、回転
角をθとした場合の sinθ と cosθ を<1.0.15>固定小数点フォーマットで与えます。

《戻り値》
なし


■４．１０  ライトをZ軸まわりに回転(sin,cos指定)

《名称》
AGLRotateLightZSC

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateLightZSC(int ln, fix1015 SinZZ, fix1015 CosZZ)

《パラメータ》
ln    : ライト番号 (AGL_LIGHT0 または AGL_LIGHT1)
SinZZ : sin値 (<1.0.15>)
CosZZ : cos値 (<1.0.15>)

《解説》
lnが示すライトをワールド座標系のZ軸まわりに回転します。パラメータとして、回転
角をθとした場合の sinθ と cosθ を<1.0.15>固定小数点フォーマットで与えます。

《戻り値》
なし


■４．１１  ライト方向を変換(マトリクス指定)

《名称》
AGLLightMulMatrix

《形式》
#include <farl.h>
#include <agl.h>
void AGLLightMulMatrix(int ln, fix1015 mx[3][3])

《パラメータ》
ln :    ライト番号 (AGL_LIGHT0 または AGL_LIGHT1)
mx :    <1.0.15>フォーマットの3×3マトリクス

《解説》
lnが示すライトのベクトルにmxを乗算します。ライトのベクトル（方向）に対して任意
の座標変換を適用することができます。

《戻り値》
なし


＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

第５章  カメラ制御


ワールド座標系に設定した仮想カメラを制御する関数群です。オブジェクトおよびライ
トは、この仮想カメラの設定にしたがってワールド座標系から正規スクリーン座標系に
変換されることになります。


■５．１    カメラのリセット

《名称》
AGLResetCamera

《形式》
#include <farl.h>
#include <agl.h>
void AGLResetCamera(void)

《パラメータ》
なし

《解説》
カメラをワールド座標系原点にリセットします。

※この関数はマクロです。

《戻り値》
なし


■５．２    カメラをX軸まわりに回転(角度指定)

《名称》
AGLRotateCameraX

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateCameraX(int angle)

《パラメータ》
angle : 回転角度 (0〜3599)

《解説》
カメラをワールド座標系のX軸まわりに回転します。角度angleの単位は0.1度(degree)
で、指定できる値の範囲は 0 〜 3599(0度〜359.9度)です。

《戻り値》
なし


■５．３    カメラをY軸まわりに回転(角度指定)

《名称》
AGLRotateCameraY

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateCameraY(int angle)

《パラメータ》
angle : 回転角度 (0〜3599)

《解説》
カメラをワールド座標系のY軸まわりに回転します。角度angleの単位は0.1度(degree)
で、指定できる値の範囲は 0 〜 3599(0度〜359.9度)です。

《戻り値》
なし


■５．４    カメラをZ軸まわりに回転(角度指定)

《名称》
AGLRotateCameraZ

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateCameraZ(int angle)

《パラメータ》
angle : 回転角度 (0〜3599)

《解説》
カメラをワールド座標系のZ軸まわりに回転します。角度angleの単位は0.1度(degree)
で、指定できる値の範囲は 0 〜 3599(0度〜359.9度)です。

《戻り値》
なし


■５．５    カメラをX軸まわりに回転(sin,cos指定)

《名称》
AGLRotateCameraXSC

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateCameraXSC(fix1015 SinXX, fix1015 CosXX)

《パラメータ》
SinXX : sin値 (<1.0.15>)
CosXX : cos値 (<1.0.15>)

《解説》
カメラをワールド座標系のX軸まわりに回転します。パラメータとして、回転角をθと
した場合の sinθ と cosθ を<1.0.15>固定小数点フォーマットで与えます。

《戻り値》
なし


■５．６    カメラをY軸まわりに回転(sin,cos指定)

《名称》
AGLRotateCameraYSC

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateCameraYSC(fix1015 SinYY, fix1015 CosYY)

《パラメータ》
SinXX : sin値 (<1.0.15>)
CosXX : cos値 (<1.0.15>)

《解説》
カメラをワールド座標系のY軸まわりに回転します。パラメータとして、回転角をθと
した場合の sinθ と cosθ を<1.0.15>固定小数点フォーマットで与えます。

《戻り値》
なし


■５．７    カメラをZ軸まわりに回転(sin,cos指定)

《名称》
AGLRotateCameraZSC

《形式》
#include <farl.h>
#include <agl.h>
void AGLRotateCameraZSC(fix1015 SinZZ, fix1015 CosZZ)

《パラメータ》
SinXX : sin値 (<1.0.15>)
CosXX : cos値 (<1.0.15>)

《解説》
カメラをワールド座標系のZ軸まわりに回転します。パラメータとして、回転角をθと
した場合の sinθ と cosθ を<1.0.15>固定小数点フォーマットで与えます。

《戻り値》
なし


■５．８    カメラの倍率を拡大/縮小

《名称》
AGLZoomCamera

《形式》
#include <farl.h>
#include <agl.h>
void AGLZoomCamera(fix187 zx, fix187 zy, fix187 zz)

《パラメータ》
zx  :   X方向の倍率 (<1.8.7>)
zy  :   Y方向の倍率 (<1.8.7>)
zz  :   Z方向の倍率 (<1.8.7>)

《解説》
カメラの倍率をワールド座標系のX,Y,Z方向にそれぞれ zx, zy, zz 倍だけ相対的に拡
大/縮小させます。zx, zy, zzはそれぞれ<1.8.7>固定小数点フォーマットです。

※この関数はマクロです。

《戻り値》
なし


■５．９    カメラを移動

《名称》
AGLTranslateCamera

《形式》
#include <farl.h>
#include <agl.h>
void AGLTranslateCamera(fix187 dx, fix187 dy, fix187 dz)

《パラメータ》
dx  :   X方向移動量 (<1.8.7>)
dy  :   Y方向移動量 (<1.8.7>)
dz  :   Z方向移動量 (<1.8.7>)

《解説》
カメラをワールド座標系のX,Y,Z方向にそれぞれ dx, dy, dzだけ移動させます。
dx, dy, dzはそれぞれ<1.8.7>固定小数点フォーマットです。

《戻り値》
なし


■５．１０  カメラを注視点に向ける

《名称》
AGLLookAtCamera

《形式》
#include <farl.h>
#include <agl.h>
void AGLLookAtCamera(fix187 x, fix187 y, fix187 z,
                     fix1015 vx,fix1015 vy,fix1015 vz)

《パラメータ》
x,y,z    :      注視点の座標 (<1.8.7>)
vx,vy,vz :      上方向ベクトル (<1.0.15>)

《解説》
カメラを座標(x,y,z)に向け、カメラの上方向をベクトル(vx,vy,vz)に合わせます。
ただし、カメラの位置と注視点との距離が 0 である場合には何もしません。

注視点(x,y,z)にはワールド座標系での座標を<1.8.7>固定小数点フォーマットで指定し
ます。

上方向ベクトル(vx,vy,vz)には、カメラ方向をZ軸方向にとった場合のベクトルを
<1.0.15>固定小数点フォーマットで指定します。
※現在のバージョンではvzは無視されて(vx,vy)の2Dベクトルとして扱われており、
この2Dベクトル(vx,vy)の長さが 1 に正規化されている必要があります。

《戻り値》
なし


■５．１１  カメラにパースをかける

《名称》
AGLPerspectiveCamera

《形式》
#include <farl.h>
#include <agl.h>
void AGLPerspectiveCamera(fix187 prs)

《パラメータ》
prs  :  パースパラメータ(<1.8.7>)

《解説》
カメラ（すなわち、ワールド座標系から正規スクリーン座標系への座標変換）に prs
だけパースをかけます。prs は<1.8.7>固定小数点フォーマットです。

※この関数はマクロです。

《戻り値》
なし


■５．１２  カメラマトリクスを幾何変換(マトリクス指定)

《名称》
AGLCameraMulMatrix

《形式》
#include <farl.h>
#include <agl.h>
void AGLCameraMulMatrix(fix187 m187[4][4], fix1015 m1015[3][3])

《パラメータ》
m187  : <1.8.7>フォーマットの4×4マトリクス
m1015 : <1.0.15>フォーマットの3×3マトリクス

《解説》
カメラ構造体のメンバー camMatrix187に対してマトリクスm187を、camMatrix1015に対
してm1015を乗算します。任意の幾何変換をカメラ（すなわち、ワールド座標系から正
規スクリーン座標系への座標変換）に適用することができます。

《戻り値》
なし


＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

第６章  描画、その他の関数


■６．１    AGLとHuC6273の初期化

《名称》
AGLInit

《形式》
#include <farl.h>
#include <agl.h>
int AGLInit(void)

《パラメータ》
なし

《解説》
AGL内部状態とHuC6273の初期化を行います。最初に一度呼び出して下さい。

HuC6273の初期化には FarlInit 関数を呼び出しており、FarlInit の戻り値が AGLInit
の戻り値となります。FarlInit の動作については『LIBFARL.Aの解説』を参照してくだ
さい。

AGLの内部状態は以下のように初期化されます。

    カメラ                AGLResetCamera()による状態

    ライト  AGL_LIGHT0    方向＝(0.0, 0.0, 1.0), 強度＝1.0(最大)
            AGL_LIGHT1    方向＝(0.0, 0.0, 1.0), 強度＝0.0(ゼロ)

《戻り値》
FarlInit の戻り値（『LIBFARL.Aの解説』参照）


■６．２    オブジェクト操作を確定

《名称》
AGLFixObj

《形式》
#include <farl.h>
#include <agl.h>
void AGLFixObj(object *obj)

《パラメータ》
obj :   オブジェクト構造体へのポインタ

《解説》
objが示すオブジェクトに対して行った操作（回転、移動、その他）を確定します。カ
メラに対する操作もここで各オブジェクトに反映されます。カメラに対して行った操
作をオブジェクトに反映するために、描画しないオブジェクトについてもこの関数を
呼び出しておく必要があります。

《戻り値》
なし


■６．３    オブジェクトを描画

《名称》
AGLPutObj

《形式》
#include <farl.h>
#include <agl.h>
void AGLPutObj(object *obj)

《パラメータ》
obj :   オブジェクト構造体へのポインタ

《解説》 
objが示すオブジェクトを描画します。オブジェクトがマテリアル情報を持っていれば、
あらかじめHuC6273の TE light coefficient registerにライティングパラメータが
セットされます。

この関数を呼び出す前に AGLFixObj関数を呼び出す必要があります。また、オブジェク
トがマテリアル情報を持っていて、そのマテリアルまたはライト強度が変更されている
場合には、そのマテリアルについて、あらかじめ AGLSetMaterial関数を呼び出してお
く必要があります。

《戻り値》
なし


■６．４    オブジェクトに対する操作を確定して描画

《名称》
AGLFixPutObj

《形式》
#include <farl.h>
#include <agl.h>
void AGLFixPutObj(object *obj)

《パラメータ》
obj :   オブジェクト構造体へのポインタ

《解説》
objが示すオブジェクトに対して行った操作（回転、移動、その他）を確定し、カメラ
に対する操作をオブジェクトに反映させた上で、オブジェクトを描画します。オブ
ジェクトがマテリアル情報を持っていれば、あらかじめHuC6273の TE light
coefficient registerにライティングパラメータがセットされます。

通常、オブジェクトの描画にはこの関数を使います。

※この関数はマクロです。

《戻り値》
なし


■６．５    フレームをスワップ

《名称》
AGLShot

《形式》
#include <farl.h>
#include <agl.h>
void AGLShot(void)

《パラメータ》
なし

《解説》
ディスプレイバッファをスワップします。それまでの描画面が表示面となり、それまで
の表示面が新たな描画面となります。また、AGL内部状態も新たなフレームの描画のた
めにリセットされます。

スプライト描画を行った場合は、スプライト描画の完了を待ち合わせてからこの関数を
呼び出してください。

また、この関数ではスワップの終了を待ち合わせませんので、この関数を呼んだ後、
スワップ動作に関係するHuC6273レジスタを変更したりスプライト描画実行を開始する
際は、スワップ動作の完了を待ち合わせてから行ってください。

《戻り値》
なし


＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

第７章  補足


■７．１    AGL使用上の注意

AGLは速度と簡潔さを重視して書かれているため、引き渡されるパラメータなどの
チェックをほとんど行なっていません。このため、範囲を越える値をセットしないよう
に注意が必要です。

AGLの各関数は、内部的に持っている１つのマトリクスに対して演算を繰り返して行く
構造になっています。以下の点に注意して下さい。

・関数を呼び出す順序を入れ替えると演算結果も変わります。関数を呼び出す順序には
  注意しましょう。例えばオブジェクトを移動させてから回転させるのと、回転させて
  から移動させるのとでは結果が異なります。

・演算を繰り返すと誤差が蓄積されます。AGLは速度を重視して浮動小数点の使用を極
  力避けて書かれているため、演算精度はあまり高くはありません。誤差があまり大き
  くならないよう注意してください。


■７．２    構造体とグローバル変数について

AGLは、グローバル変数として以下の２つを持っています。すべて関数を通して操作す
るため、ユーザが直接手を加える事はありません。

・ カメラ情報

    struct camera __AGLCamera;

    カメラ情報を保持しています。構造体 camera（カメラ構造体）は以下のように定
    義されています。

    typedef struct camera {
        fix187      camMatrix187[4][4];     /* カメラマトリクス1            */
        fix1015     camMatrix1015[3][3];    /* カメラマトリクス2            */
        int         camChanged;             /* マトリクスの変更フラグ       */
    } camera;

・ ライト情報

    struct light __AGLLight[2];

    ２つのライトの情報を保持しています。構造体 light（ライト構造体）は以下のよ
    うに定義されています。

    typedef struct light {
        fix1015     lightVector[3];         /* ライトのベクトル（方向）     */
        fix1015     lightStrength;          /* ライトの強度                 */
        int         lightChanged;           /* ライトベクトル変更フラグ     */
    } light;


カメラ構造体中の camMatrix187 と camMatrix1015 は、ワールド座標系から正規スク
リーン座標系への座標変換マトリクスを保持します。

オブジェクト構造体（第２章『オブジェクト制御』参照）中の objToWorld187 と
objToWorld1015 は、オブジェクトのモデル座標系からワールド座標系への座標変換マ
トリクスを保持します。objMatrix と nrmMatrix は、それぞれ camMatrix187 と
camMatrix1015 のコピーです。オブジェクト描画時には、objToWorld187 に objMatrix
を乗算した結果がHuC6273の TE object matrixにセットされ、objToWorld1015 に
nrmMatrix を乗算した結果がHuC6273の TE normal matrixにセットされます。

オブジェクト構造体、カメラ構造体、ライト構造体のそれぞれのメンバー objChanged,
camChanged, lightChanged は、無駄な演算や転送を省くための内部フラグで、それぞ
れ以下の状態を保持します。

    objChanged
    ----------
        -2    オブジェクトがリセットされた状態。objToWorld187マトリクス、
              objToWorld1015マトリクス共に単位行列。

        -1    objToWorld187マトリクスのみ変更されている。
              objToWorld1015マトリクスは単位行列。

         1    objToWorld187マトリクス、objToWorld1015マトリクスともに変更され
              ている。

    camChanged
    ----------
        -2      カメラのリセットのみ行われている。
                camMatrix187, camMatrix1015共に単位行列。

        -1      camMatrix187のみ変更されている。camMatrix1871015マトリクスは単
                位行列。

         1      camMatrix187, camMatrix1015ともに変更されている。

    lightChanged
    ------------
         0      ライトはリセットされた状態。

         1      ライト方向は変更されている。

        -1      ライトベクターは既に転送されている。


＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

《著作権及び登録商標等》

・LIBAGL.A 及び LIBAGL.TXT（以下、"本ソフトウェア"という）は、ＰＣ−ＦＸＧＡ用
  のソフトウェア開発ツールの一部です。本ソフトウェアを、ＰＣ−ＦＸ、ＰＣ−ＦＸ
  ＧＡ用のソフトウェア開発以外の目的で使用しないで下さい。

・本ソフトウェアを使用した結果、直接及び間接的に生じた損害について、株式会社ハ
  ドソンは、一切の責任または債務を負わないものとします。

・本ソフトウェアの操作方法、技術的内容、その他の質問について、株式会社ハドソン
  では、直接お答えしていません。お問い合わせはご遠慮下さい。

・本ソフトウェアの使用に際し、「ソフトウェアのご使用条件」をよくご覧いただき、
  ご利用下さいますようお願い致します。


MS-DOSは米国マイクロソフト社の登録商標です。
その他、記載されている会社名、製品名は、各社の登録商標または商標です。


                                                           (C)1995 HUDSON SOFT
                                                           (C)1995 KUBOTA CORP.


